---
title: PdfAPI.Core overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.Core
reference_type: package
---

# PdfAPI.Core overview

> **Documentation context:** Packaged Component (NuGet)
> **Documented via:** PdfAPI (PdfAPI\PdfAPI.csproj)

PdfAPI.Core is the shared contracts-and-primitives layer of the `IT.CoreServices.PDFAPI` repository. It defines the request, result, document, page-range, and tracking types used by the `PdfAPI` Web API service, the `PdfAPI.SyncFusionCore` processor library, and the `PdfAPI.Client` package, and it ships a small, stateless set of iTextSharp-backed PDF utilities. It sits at depth 1 of the repository's reference graph — depended on by every other project in the repository, while depending on no in-repo project itself.

## Purpose
- Define the shared request/result/options/tracking DTOs and enums (`PdfRequest`, `ConvertRequest`, `MergeRequest`, `ExtractPagesRequest`, `PdfOptions`, `PdfResult`, `PdfTrackingInfo`, `PdfTrackingMetadata`, and their supporting enums) that form the wire and in-process vocabulary shared by the API service, the processor library, and the client package.
- Provide `Document`, `DocumentRange`, `DocumentRangeFactory`, and `PageRange`/`IPageRange` types that model an in-memory-or-on-disk file and the page selections made against it, including page-expression parsing (`"1-5,7,9-*,*"`).
- Provide `PdfClientService`, the only behaviour-bearing type in the library — a static, stateless facade over iTextSharp 5.5.11 offering PDF inspection, transformation, and guard operations that execute entirely in the caller's process with no network or database access.
- Define cache request/result contracts (`PdfAPI.Core.Cache`) that describe a cache lookup/write outcome without implementing any cache store.
- Consumed by the `PdfAPI` Web API service, the `PdfAPI.SyncFusionCore` processor library, and the `PdfAPI.Client` package, both as a same-repo project reference (`PdfAPI`) and as packaged source/binary content bundled into two downstream NuGet packages (`Pdf.Local.Client`, `PdfAPI.Client`).

## Responsibilities
- Own the shared PDF request/result/options/tracking contract surface consumed across the repository.
- Provide the sole behaviour-bearing PDF utility type (`PdfClientService`) for inspection, flattening, validation, and page extraction.
- Model file and page-range selection (`Document`, `DocumentRange`, `PageRange`) including destructive file-system lifecycle semantics.
- Encode/decode the file-name tracking-prefix convention (`PdfTrackingMetadata`) used to correlate files across the PDF platform.

## Key components
- `PdfClientService`: static facade over iTextSharp 5.5.11 for PDF inspection (`IsPdf`, `Version`, `GetPageCount`, `HasFormFields`), transformation (`Flatten`, `ExtractPages`/`ExtractPageRanges`), and validation (`ValidatePdf`).
- `Document`: in-memory-or-on-disk representation of a single file, with destructive `Dispose()`/`Delete()` semantics.
- `DocumentRange` / `PageRange` / `DocumentRangeFactory`: page-selection modeling and page-expression parsing.
- `PdfRequest` family (`ConvertRequest`, `MergeRequest`, `ExtractPagesRequest`): request contracts for conversion, merge, and extraction operations.
- `PdfResult`: result contract returned by every operation, carrying status, processor type, and output document.
- `PdfTrackingMetadata` / `PdfTrackingInfo`: file-name tracking-prefix encoding/decoding and tracking snapshots.
- `PdfAPI.Core.Cache` types (`PdfCacheRequest`, `PdfCacheCreationRequest`, `PdfCacheResult`, `CacheType`): cache lookup/write contracts with no implementing cache store.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [Security and authorization](security-authorization.md)
- [API reference](api/index.md)

## Sources
- `PdfAPI.Core\PdfAPI.Core.csproj`
- `PdfAPI.Core\Document.cs`
- `PdfAPI.Core\Extract\DocumentRange.cs`
- `PdfAPI.Core\Extract\PageRange.cs`
- `PdfAPI.Core\Services\PdfClientService.cs`
- `PdfAPI.Core\PdfTrackingMetadata.cs`
- `PdfAPI.Core\Cache\CacheType.cs`
- `PdfAPI\PdfAPI.csproj`